Reading Activity Summaries#

The Scripting app provides access to daily activity summary data from Apple Health using the global function Health.queryActivitySummaries(). These summaries represent Move, Exercise, and Stand goals tracked by Apple Watch, along with completion metrics and historical trends.

This API is ideal for displaying daily ring data or analyzing long-term fitness trends.

What Is an Activity Summary?#

An HealthActivitySummary provides a high-level overview of a day’s Apple Watch activity:

• Move (Active Energy Burned)

  • activeEnergyBurned(unit: HealthUnit): number
  • activeEnergyBurnedGoal(unit: HealthUnit): number

• Exercise (Minutes)

  • appleExerciseTime(unit: HealthUnit): number
  • appleExerciseTimeGoal(unit: HealthUnit): number

• Stand (Hours)

  • appleStandHours(unit: HealthUnit): number
  • appleStandHoursGoal(unit: HealthUnit): number

• Date Information

  • dateComponents: DateComponents – a DateComponents object containing at least year, month, and day.

API Overview#

1Health.queryActivitySummaries(
2  options?: {
3    start: DateComponents
4    end: DateComponents
5  }
6): Promise<HealthActivitySummary[]>

Parameters#

If you omit the options, the API returns all available summaries (up to system limits). Summaries are returned sorted by date in ascending order.

Example: Read Last 7 Days’ Activity Summaries#

1async function fetchLastWeek() {
2  // Build DateComponents for the date range
3  const today = new Date()
4  const sevenDaysAgo = new Date(
5    today.getFullYear(),
6    today.getMonth(),
7    today.getDate() - 6
8  )
9
10  const startComponents = DateComponents.fromDate(sevenDaysAgo)
11  const endComponents = DateComponents.fromDate(today)
12
13  // Query activity summaries
14  const summaries = await Health.queryActivitySummaries({
15    start: startComponents,
16    end: endComponents,
17  })
18
19  // Iterate and log each day’s data
20  for (const summary of summaries) {
21    const date = summary.dateComponents.date
22    console.log(`Date: ${date?.toDateString()}`)
23
24    const kcal = summary.activeEnergyBurned(HealthUnit.kilocalorie())
25    const kcalGoal = summary.activeEnergyBurnedGoal(HealthUnit.kilocalorie())
26    const exerciseMin = summary.appleExerciseTime(HealthUnit.minute())
27    const standHrs = summary.appleStandHours(HealthUnit.count())
28
29    console.log(` Move:    ${kcal} / ${kcalGoal} kcal`)
30    console.log(` Exercise: ${exerciseMin} min`)
31    console.log(` Stand:    ${standHrs} hrs`)
32    console.log('---')
33  }
34}
35
36fetchLastWeek()

Notes#

• DateComponents must include at least year, month, and day—other fields (hour, minute) are ignored for daily summaries.
• Each metric method returns a raw number in the specified unit.
• Use HealthUnit factory methods (e.g., kilocalorie(), minute(), count()) to specify units.
• Days with no data (e.g., Apple Watch off-wrist) may be omitted from results.

Summary#

1. Call Health.queryActivitySummaries({ start, end }) with DateComponents to specify your date range.
2. Receive an array of HealthActivitySummary, sorted ascending by date.
3. Use the summary’s methods to read actual vs. goal values for Move, Exercise, and Stand.
4. Convert and display the numbers in your UI or analytics.